home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 October: Mac OS SDK / Dev.CD Oct 00 SDK1.toast / Development Kits / Mac OS / Text Encoding Converter 1.5 / Headers / UnicodeConverter.h < prev   
Encoding:
C/C++ Source or Header  |  1999-09-17  |  15.2 KB  |  431 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        UnicodeConverter.h
  3.  
  4.      Contains:    Types, constants, and prototypes for Unicode Converter
  5.  
  6.      Version:    Mac OS 8.7
  7.  
  8.      DRI:        Julio Gonzalez
  9.  
  10.      Copyright:    © 1994-1999 by Apple Computer, Inc., all rights reserved.
  11.  
  12.      Warning:    *** APPLE INTERNAL USE ONLY ***
  13.                  This file may contain unreleased API's
  14.  
  15.      BuildInfo:    Built by:            BuildGod
  16.                  On:                    09/17/99 11:19 AM
  17.                  With Interfacer:    3.0d13   (MPW PowerPC)
  18.                  From:                UnicodeConverter.i
  19.                      Revision:        14
  20.                      Dated:            5/20/99
  21.                      Last change by:    ngk
  22.                      Last comment:    Add CarbonLib exportset to ProcPtrs
  23.  
  24.      Bugs:        Report bugs to Radar component "System Interfaces", "Latest"
  25.                  List the version information (from above) in the Problem Description.
  26.  
  27. */
  28. #ifndef __UNICODECONVERTER__
  29. #define __UNICODECONVERTER__
  30.  
  31. #ifndef __MACTYPES__
  32. #include <MacTypes.h>
  33. #endif
  34.  
  35. #ifndef __TEXTCOMMON__
  36. #include <TextCommon.h>
  37. #endif
  38.  
  39. #ifndef __MIXEDMODE__
  40. #include <MixedMode.h>
  41. #endif
  42.  
  43.  
  44.  
  45.  
  46. #if PRAGMA_ONCE
  47. #pragma once
  48. #endif
  49.  
  50. #ifdef __cplusplus
  51. extern "C" {
  52. #endif
  53.  
  54. #if PRAGMA_IMPORT
  55. #pragma import on
  56. #endif
  57.  
  58. #if PRAGMA_STRUCT_ALIGN
  59.     #pragma options align=mac68k
  60. #elif PRAGMA_STRUCT_PACKPUSH
  61.     #pragma pack(push, 2)
  62. #elif PRAGMA_STRUCT_PACK
  63.     #pragma pack(2)
  64. #endif
  65.  
  66. /* Unicode conversion contexts: */
  67. typedef struct OpaqueTextToUnicodeInfo*  TextToUnicodeInfo;
  68. typedef struct OpaqueUnicodeToTextInfo*  UnicodeToTextInfo;
  69. typedef struct OpaqueUnicodeToTextRunInfo*  UnicodeToTextRunInfo;
  70. typedef const TextToUnicodeInfo         ConstTextToUnicodeInfo;
  71. typedef const UnicodeToTextInfo         ConstUnicodeToTextInfo;
  72. /* UnicodeMapVersion type & values */
  73. typedef SInt32                             UnicodeMapVersion;
  74. enum {
  75.     kUnicodeUseLatestMapping    = -1,
  76.     kUnicodeUseHFSPlusMapping    = 4
  77. };
  78.  
  79. /* Types used in conversion */
  80.  
  81. struct UnicodeMapping {
  82.     TextEncoding                     unicodeEncoding;
  83.     TextEncoding                     otherEncoding;
  84.     UnicodeMapVersion                 mappingVersion;
  85. };
  86. typedef struct UnicodeMapping            UnicodeMapping;
  87. typedef UnicodeMapping *                UnicodeMappingPtr;
  88.  
  89. typedef const UnicodeMapping *            ConstUnicodeMappingPtr;
  90. /* Control flags for ConvertFromUnicodeToText and ConvertFromTextToUnicode */
  91. enum {
  92.     kUnicodeUseFallbacksBit        = 0,
  93.     kUnicodeKeepInfoBit            = 1,
  94.     kUnicodeDirectionalityBits    = 2,
  95.     kUnicodeVerticalFormBit        = 4,
  96.     kUnicodeLooseMappingsBit    = 5,
  97.     kUnicodeStringUnterminatedBit = 6,
  98.     kUnicodeTextRunBit            = 7,
  99.     kUnicodeKeepSameEncodingBit    = 8,
  100.     kUnicodeForceASCIIRangeBit    = 9,
  101.     kUnicodeNoHalfwidthCharsBit    = 10,
  102.     kUnicodeTextRunHeuristicsBit = 11
  103. };
  104.  
  105. enum {
  106.     kUnicodeUseFallbacksMask    = 1L << kUnicodeUseFallbacksBit,
  107.     kUnicodeKeepInfoMask        = 1L << kUnicodeKeepInfoBit,
  108.     kUnicodeDirectionalityMask    = 3L << kUnicodeDirectionalityBits,
  109.     kUnicodeVerticalFormMask    = 1L << kUnicodeVerticalFormBit,
  110.     kUnicodeLooseMappingsMask    = 1L << kUnicodeLooseMappingsBit,
  111.     kUnicodeStringUnterminatedMask = 1L << kUnicodeStringUnterminatedBit,
  112.     kUnicodeTextRunMask            = 1L << kUnicodeTextRunBit,
  113.     kUnicodeKeepSameEncodingMask = 1L << kUnicodeKeepSameEncodingBit,
  114.     kUnicodeForceASCIIRangeMask    = 1L << kUnicodeForceASCIIRangeBit,
  115.     kUnicodeNoHalfwidthCharsMask = 1L << kUnicodeNoHalfwidthCharsBit,
  116.     kUnicodeTextRunHeuristicsMask = 1L << kUnicodeTextRunHeuristicsBit
  117. };
  118.  
  119. /* Values for kUnicodeDirectionality field */
  120. enum {
  121.     kUnicodeDefaultDirection    = 0,
  122.     kUnicodeLeftToRight            = 1,
  123.     kUnicodeRightToLeft            = 2
  124. };
  125.  
  126. /* Directionality masks for control flags */
  127. enum {
  128.     kUnicodeDefaultDirectionMask = kUnicodeDefaultDirection << kUnicodeDirectionalityBits,
  129.     kUnicodeLeftToRightMask        = kUnicodeLeftToRight << kUnicodeDirectionalityBits,
  130.     kUnicodeRightToLeftMask        = kUnicodeRightToLeft << kUnicodeDirectionalityBits
  131. };
  132.  
  133. /* Control flags for TruncateForUnicodeToText: */
  134. /*
  135.    Now TruncateForUnicodeToText uses control flags from the same set as used by
  136.    ConvertFromTextToUnicode, ConvertFromUnicodeToText, etc., but only
  137.    kUnicodeStringUnterminatedMask is meaningful for TruncateForUnicodeToText.
  138.    
  139.    Previously two special control flags were defined for TruncateForUnicodeToText:
  140.           kUnicodeTextElementSafeBit = 0
  141.           kUnicodeRestartSafeBit = 1
  142.    However, neither of these was implemented.
  143.    Instead of implementing kUnicodeTextElementSafeBit, we now use
  144.    kUnicodeStringUnterminatedMask since it accomplishes the same thing and avoids
  145.    having special flags just for TruncateForUnicodeToText
  146.    Also, kUnicodeRestartSafeBit is unnecessary, since restart-safeness is handled by
  147.    setting kUnicodeKeepInfoBit with ConvertFromUnicodeToText.
  148.    If TruncateForUnicodeToText is called with one or both of the old special control
  149.    flags set (bits 0 or 1), it will not generate a paramErr, but the old bits have no
  150.    effect on its operation.
  151. */
  152.  
  153. /* Filter bits for filter field in QueryUnicodeMappings and CountUnicodeMappings: */
  154. enum {
  155.     kUnicodeMatchUnicodeBaseBit    = 0,
  156.     kUnicodeMatchUnicodeVariantBit = 1,
  157.     kUnicodeMatchUnicodeFormatBit = 2,
  158.     kUnicodeMatchOtherBaseBit    = 3,
  159.     kUnicodeMatchOtherVariantBit = 4,
  160.     kUnicodeMatchOtherFormatBit    = 5
  161. };
  162.  
  163. enum {
  164.     kUnicodeMatchUnicodeBaseMask = 1L << kUnicodeMatchUnicodeBaseBit,
  165.     kUnicodeMatchUnicodeVariantMask = 1L << kUnicodeMatchUnicodeVariantBit,
  166.     kUnicodeMatchUnicodeFormatMask = 1L << kUnicodeMatchUnicodeFormatBit,
  167.     kUnicodeMatchOtherBaseMask    = 1L << kUnicodeMatchOtherBaseBit,
  168.     kUnicodeMatchOtherVariantMask = 1L << kUnicodeMatchOtherVariantBit,
  169.     kUnicodeMatchOtherFormatMask = 1L << kUnicodeMatchOtherFormatBit
  170. };
  171.  
  172. /* Control flags for SetFallbackUnicodeToText */
  173. enum {
  174.     kUnicodeFallbackSequencingBits = 0
  175. };
  176.  
  177. enum {
  178.     kUnicodeFallbackSequencingMask = 3L << kUnicodeFallbackSequencingBits,
  179.     kUnicodeFallbackInterruptSafeMask = 1L << 2                    /* To indicate that caller fallback routine doesn’t move memory*/
  180. };
  181.  
  182. /* values for kUnicodeFallbackSequencing field */
  183. enum {
  184.     kUnicodeFallbackDefaultOnly    = 0L,
  185.     kUnicodeFallbackCustomOnly    = 1L,
  186.     kUnicodeFallbackDefaultFirst = 2L,
  187.     kUnicodeFallbackCustomFirst    = 3L
  188. };
  189.  
  190.  
  191. /* Caller-supplied entry point to a fallback handler */
  192. typedef CALLBACK_API( OSStatus , UnicodeToTextFallbackProcPtr )(UniChar *iSrcUniStr, ByteCount iSrcUniStrLen, ByteCount *oSrcConvLen, TextPtr oDestStr, ByteCount iDestStrLen, ByteCount *oDestConvLen, LogicalAddress iInfoPtr, ConstUnicodeMappingPtr iUnicodeMappingPtr);
  193. typedef STACK_UPP_TYPE(UnicodeToTextFallbackProcPtr)             UnicodeToTextFallbackUPP;
  194. #if OPAQUE_UPP_TYPES
  195.     EXTERN_API(UnicodeToTextFallbackUPP)
  196.     NewUnicodeToTextFallbackUPP       (UnicodeToTextFallbackProcPtr userRoutine);
  197.  
  198.     EXTERN_API(void)
  199.     DisposeUnicodeToTextFallbackUPP    (UnicodeToTextFallbackUPP userUPP);
  200.  
  201.     EXTERN_API(OSStatus)
  202.     InvokeUnicodeToTextFallbackUPP    (UniChar *            iSrcUniStr,
  203.                                     ByteCount                iSrcUniStrLen,
  204.                                     ByteCount *                oSrcConvLen,
  205.                                     TextPtr                    oDestStr,
  206.                                     ByteCount                iDestStrLen,
  207.                                     ByteCount *                oDestConvLen,
  208.                                     LogicalAddress            iInfoPtr,
  209.                                     ConstUnicodeMappingPtr    iUnicodeMappingPtr,
  210.                                     UnicodeToTextFallbackUPP userUPP);
  211.  
  212. #else
  213.     enum { uppUnicodeToTextFallbackProcInfo = 0x003FFFF0 };         /* pascal 4_bytes Func(4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes) */
  214.     #define NewUnicodeToTextFallbackUPP(userRoutine)                 (UnicodeToTextFallbackUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppUnicodeToTextFallbackProcInfo, GetCurrentArchitecture())
  215.     #define DisposeUnicodeToTextFallbackUPP(userUPP)                 DisposeRoutineDescriptor(userUPP)
  216.     #define InvokeUnicodeToTextFallbackUPP(iSrcUniStr, iSrcUniStrLen, oSrcConvLen, oDestStr, iDestStrLen, oDestConvLen, iInfoPtr, iUnicodeMappingPtr, userUPP)  CALL_EIGHT_PARAMETER_UPP((userUPP), uppUnicodeToTextFallbackProcInfo, (iSrcUniStr), (iSrcUniStrLen), (oSrcConvLen), (oDestStr), (iDestStrLen), (oDestConvLen), (iInfoPtr), (iUnicodeMappingPtr))
  217. #endif
  218. /* support for pre-Carbon UPP routines: NewXXXProc and CallXXXProc */
  219. #define NewUnicodeToTextFallbackProc(userRoutine)                 NewUnicodeToTextFallbackUPP(userRoutine)
  220. #define CallUnicodeToTextFallbackProc(userRoutine, iSrcUniStr, iSrcUniStrLen, oSrcConvLen, oDestStr, iDestStrLen, oDestConvLen, iInfoPtr, iUnicodeMappingPtr) InvokeUnicodeToTextFallbackUPP(iSrcUniStr, iSrcUniStrLen, oSrcConvLen, oDestStr, iDestStrLen, oDestConvLen, iInfoPtr, iUnicodeMappingPtr, userRoutine)
  221. /* Function prototypes */
  222. #if TARGET_CPU_68K && !TARGET_RT_MAC_CFM
  223. /*
  224.       Routine to Initialize the Unicode Converter and cleanup once done with it. 
  225.       These routines must be called from Static Library clients.
  226. */
  227. EXTERN_API( OSStatus )
  228. InitializeUnicodeConverter        (StringPtr                 TECFileName);
  229.  
  230. EXTERN_API( void )
  231. TerminateUnicodeConverter        (void);
  232.  
  233. /* Note: the old names (InitializeUnicode, TerminateUnicode) for the above are still exported.*/
  234. #endif  /* TARGET_CPU_68K && !TARGET_RT_MAC_CFM */
  235.  
  236. EXTERN_API( OSStatus )
  237. CreateTextToUnicodeInfo            (ConstUnicodeMappingPtr  iUnicodeMapping,
  238.                                  TextToUnicodeInfo *    oTextToUnicodeInfo);
  239.  
  240. EXTERN_API( OSStatus )
  241. CreateTextToUnicodeInfoByEncoding (TextEncoding         iEncoding,
  242.                                  TextToUnicodeInfo *    oTextToUnicodeInfo);
  243.  
  244. EXTERN_API( OSStatus )
  245. CreateUnicodeToTextInfo            (ConstUnicodeMappingPtr  iUnicodeMapping,
  246.                                  UnicodeToTextInfo *    oUnicodeToTextInfo);
  247.  
  248. EXTERN_API( OSStatus )
  249. CreateUnicodeToTextInfoByEncoding (TextEncoding         iEncoding,
  250.                                  UnicodeToTextInfo *    oUnicodeToTextInfo);
  251.  
  252. EXTERN_API( OSStatus )
  253. CreateUnicodeToTextRunInfo        (ItemCount                 iNumberOfMappings,
  254.                                  const UnicodeMapping     iUnicodeMappings[],
  255.                                  UnicodeToTextRunInfo *    oUnicodeToTextInfo);
  256.  
  257. EXTERN_API( OSStatus )
  258. CreateUnicodeToTextRunInfoByEncoding (ItemCount         iNumberOfEncodings,
  259.                                  const TextEncoding     iEncodings[],
  260.                                  UnicodeToTextRunInfo *    oUnicodeToTextInfo);
  261.  
  262. EXTERN_API( OSStatus )
  263. CreateUnicodeToTextRunInfoByScriptCode (ItemCount         iNumberOfScriptCodes,
  264.                                  const ScriptCode         iScripts[],
  265.                                  UnicodeToTextRunInfo *    oUnicodeToTextInfo);
  266.  
  267. /* Change the TextToUnicodeInfo to another mapping. */
  268. EXTERN_API( OSStatus )
  269. ChangeTextToUnicodeInfo            (TextToUnicodeInfo         ioTextToUnicodeInfo,
  270.                                  ConstUnicodeMappingPtr  iUnicodeMapping);
  271.  
  272. /* Change the UnicodeToTextInfo to another mapping. */
  273. EXTERN_API( OSStatus )
  274. ChangeUnicodeToTextInfo            (UnicodeToTextInfo         ioUnicodeToTextInfo,
  275.                                  ConstUnicodeMappingPtr  iUnicodeMapping);
  276.  
  277.  
  278. EXTERN_API( OSStatus )
  279. DisposeTextToUnicodeInfo        (TextToUnicodeInfo *    ioTextToUnicodeInfo);
  280.  
  281. EXTERN_API( OSStatus )
  282. DisposeUnicodeToTextInfo        (UnicodeToTextInfo *    ioUnicodeToTextInfo);
  283.  
  284. EXTERN_API( OSStatus )
  285. DisposeUnicodeToTextRunInfo        (UnicodeToTextRunInfo *    ioUnicodeToTextRunInfo);
  286.  
  287. EXTERN_API( OSStatus )
  288. ConvertFromTextToUnicode        (TextToUnicodeInfo         iTextToUnicodeInfo,
  289.                                  ByteCount                 iSourceLen,
  290.                                  ConstLogicalAddress     iSourceStr,
  291.                                  OptionBits             iControlFlags,
  292.                                  ItemCount                 iOffsetCount,
  293.                                  ByteOffset             iOffsetArray[], /* can be NULL */
  294.                                  ItemCount *            oOffsetCount, /* can be NULL */
  295.                                  ByteOffset             oOffsetArray[], /* can be NULL */
  296.                                  ByteCount                 iOutputBufLen,
  297.                                  ByteCount *            oSourceRead,
  298.                                  ByteCount *            oUnicodeLen,
  299.                                  UniCharArrayPtr         oUnicodeStr);
  300.  
  301. EXTERN_API( OSStatus )
  302. ConvertFromUnicodeToText        (UnicodeToTextInfo         iUnicodeToTextInfo,
  303.                                  ByteCount                 iUnicodeLen,
  304.                                  ConstUniCharArrayPtr     iUnicodeStr,
  305.                                  OptionBits             iControlFlags,
  306.                                  ItemCount                 iOffsetCount,
  307.                                  ByteOffset             iOffsetArray[], /* can be NULL */
  308.                                  ItemCount *            oOffsetCount, /* can be NULL */
  309.                                  ByteOffset             oOffsetArray[], /* can be NULL */
  310.                                  ByteCount                 iOutputBufLen,
  311.                                  ByteCount *            oInputRead,
  312.                                  ByteCount *            oOutputLen,
  313.                                  LogicalAddress         oOutputStr);
  314.  
  315. EXTERN_API( OSStatus )
  316. ConvertFromUnicodeToTextRun        (UnicodeToTextRunInfo     iUnicodeToTextInfo,
  317.                                  ByteCount                 iUnicodeLen,
  318.                                  ConstUniCharArrayPtr     iUnicodeStr,
  319.                                  OptionBits             iControlFlags,
  320.                                  ItemCount                 iOffsetCount,
  321.                                  ByteOffset             iOffsetArray[], /* can be NULL */
  322.                                  ItemCount *            oOffsetCount, /* can be NULL */
  323.                                  ByteOffset             oOffsetArray[], /* can be NULL */
  324.                                  ByteCount                 iOutputBufLen,
  325.                                  ByteCount *            oInputRead,
  326.                                  ByteCount *            oOutputLen,
  327.                                  LogicalAddress         oOutputStr,
  328.                                  ItemCount                 iEncodingRunBufLen,
  329.                                  ItemCount *            oEncodingRunOutLen,
  330.                                  TextEncodingRun         oEncodingRuns[]);
  331.  
  332. EXTERN_API( OSStatus )
  333. ConvertFromUnicodeToScriptCodeRun (UnicodeToTextRunInfo  iUnicodeToTextInfo,
  334.                                  ByteCount                 iUnicodeLen,
  335.                                  ConstUniCharArrayPtr     iUnicodeStr,
  336.                                  OptionBits             iControlFlags,
  337.                                  ItemCount                 iOffsetCount,
  338.                                  ByteOffset             iOffsetArray[], /* can be NULL */
  339.                                  ItemCount *            oOffsetCount, /* can be NULL */
  340.                                  ByteOffset             oOffsetArray[], /* can be NULL */
  341.                                  ByteCount                 iOutputBufLen,
  342.                                  ByteCount *            oInputRead,
  343.                                  ByteCount *            oOutputLen,
  344.                                  LogicalAddress         oOutputStr,
  345.                                  ItemCount                 iScriptRunBufLen,
  346.                                  ItemCount *            oScriptRunOutLen,
  347.                                  ScriptCodeRun             oScriptCodeRuns[]);
  348.  
  349. /* Truncate a multibyte string at a safe place. */
  350. EXTERN_API( OSStatus )
  351. TruncateForTextToUnicode        (ConstTextToUnicodeInfo  iTextToUnicodeInfo,
  352.                                  ByteCount                 iSourceLen,
  353.                                  ConstLogicalAddress     iSourceStr,
  354.                                  ByteCount                 iMaxLen,
  355.                                  ByteCount *            oTruncatedLen);
  356.  
  357. /* Truncate a Unicode string at a safe place. */
  358. EXTERN_API( OSStatus )
  359. TruncateForUnicodeToText        (ConstUnicodeToTextInfo  iUnicodeToTextInfo,
  360.                                  ByteCount                 iSourceLen,
  361.                                  ConstUniCharArrayPtr     iSourceStr,
  362.                                  OptionBits             iControlFlags,
  363.                                  ByteCount                 iMaxLen,
  364.                                  ByteCount *            oTruncatedLen);
  365.  
  366. /* Convert a Pascal string to Unicode string. */
  367. EXTERN_API( OSStatus )
  368. ConvertFromPStringToUnicode        (TextToUnicodeInfo         iTextToUnicodeInfo,
  369.                                  ConstStr255Param         iPascalStr,
  370.                                  ByteCount                 iOutputBufLen,
  371.                                  ByteCount *            oUnicodeLen,
  372.                                  UniCharArrayPtr         oUnicodeStr);
  373.  
  374. /* Convert a Unicode string to Pascal string. */
  375. EXTERN_API( OSStatus )
  376. ConvertFromUnicodeToPString        (UnicodeToTextInfo         iUnicodeToTextInfo,
  377.                                  ByteCount                 iUnicodeLen,
  378.                                  ConstUniCharArrayPtr     iUnicodeStr,
  379.                                  Str255                 oPascalStr);
  380.  
  381. /* Count the available conversion mappings. */
  382. EXTERN_API( OSStatus )
  383. CountUnicodeMappings            (OptionBits             iFilter,
  384.                                  ConstUnicodeMappingPtr  iFindMapping,
  385.                                  ItemCount *            oActualCount);
  386.  
  387. /* Get a list of the available conversion mappings. */
  388. EXTERN_API( OSStatus )
  389. QueryUnicodeMappings            (OptionBits             iFilter,
  390.                                  ConstUnicodeMappingPtr  iFindMapping,
  391.                                  ItemCount                 iMaxCount,
  392.                                  ItemCount *            oActualCount,
  393.                                  UnicodeMapping         oReturnedMappings[]);
  394.  
  395. /* Setup the fallback handler for converting Unicode To Text. */
  396. EXTERN_API( OSStatus )
  397. SetFallbackUnicodeToText        (UnicodeToTextInfo         iUnicodeToTextInfo,
  398.                                  UnicodeToTextFallbackUPP  iFallback,
  399.                                  OptionBits             iControlFlags,
  400.                                  LogicalAddress         iInfoPtr);
  401.  
  402. /* Setup the fallback handler for converting Unicode To TextRuns. */
  403. EXTERN_API( OSStatus )
  404. SetFallbackUnicodeToTextRun        (UnicodeToTextRunInfo     iUnicodeToTextRunInfo,
  405.                                  UnicodeToTextFallbackUPP  iFallback,
  406.                                  OptionBits             iControlFlags,
  407.                                  LogicalAddress         iInfoPtr);
  408.  
  409.  
  410.  
  411. #if PRAGMA_STRUCT_ALIGN
  412.     #pragma options align=reset
  413. #elif PRAGMA_STRUCT_PACKPUSH
  414.     #pragma pack(pop)
  415. #elif PRAGMA_STRUCT_PACK
  416.     #pragma pack()
  417. #endif
  418.  
  419. #ifdef PRAGMA_IMPORT_OFF
  420. #pragma import off
  421. #elif PRAGMA_IMPORT
  422. #pragma import reset
  423. #endif
  424.  
  425. #ifdef __cplusplus
  426. }
  427. #endif
  428.  
  429. #endif /* __UNICODECONVERTER__ */
  430.  
  431.